PCX 

INTERNATIONAL APPUCATION PUBLISHED UNDER THE PATENT COOPERATION TREATY (PCT) 



(51) International Patent Classification ^ : 
G06F 11/14 



(II) International Publication Number: 
(43) International Publication Date: 



WO 95/13580 

18 May 1995 (18.05.95) 



(21) International Application Nnmber: 



PCT/US94/1291S 



(22) International FDing Date: 9 November 1994 (09. 1 1.94) 



9 November 1993 (09.1 1 .93) US 



(72) Inventors: FLETCHER, Douglas, J.; 340 Wekiva Trail West, 
Longwood, FL 32779 (US). DEVOS, Steven, Robert; 1529 
3rd Street, KirWand. WA 98033 (US). 

(74) Agent: HJESLER, Martin, C; Fliesler, Dubb, Meyer and 
Lovejoy, Suite 400, Four Embarcadero Center, San Fran- 
cisco, CA 9411 1-4156 (US). 



With international search report. 
Before the expiration of the time limit for amending the 
claims and to be republished in the event of the receipt of 
amendments. 



(54) Title: DATA BACKUP AND RESTORE SYSTEM FOR A COMPUTER NETWORK 



I I 



(57) Abstract 

A computet network having a number of workstations nnming disparate operating systems and a file server having a tape driver for 
backup and restore of data on die network. The filter server runs a generic remote file system (GRFS) and workstations ran GRF5 agent 
programs which allow the GRFS file system to access data within a wortcstation having a given GRFS agent program. The GRFS file 
system interfaces with each GRFS agent program via a command/response paradigm, with the messages being structured to support the 
disparate operating systems for backup and restore, to allow data to be interchanged between the disparate operating systems, and to allow 
independent multiple users of the network to request simultaneously backup or restore. 
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data area is at most 1.024 bytes. Furthermore, there are 
several fields within the DBLK structure, which are 
actually pointers to information within the DBLK data 
area. These pointers are generated as offsets from the 
beginning of the DBLK structure. For example, if the 
DBLK common area is 80 bytes long and the first item 
within the data area is the object's name, then the 
object name field would be set to 8 0 in order to point to 
the first byte following the DBLK common structure. The 
individual fields within the common DBLK structure that 
are manipulated by the GRFS agent programs are described 
in detail below under the heading "DBLK Fields". 

In order to implement a backup and restore function 
for a given computer 12, that computer 12 should 
advertise its capability for this purpose. Not every 
computer 12 in the network 10 is necessarily running a 
GRFS agent program so as to be able to have its data 
backed up. Consequently, the GRFS agent programs will 
"advertise" their capability as a GRFS agent over the 
network lO. This may be accomplished using the NRL 
resource advertisement function. The GRFS agent resource 
advertisement publishes the logical name of the 
particular agent's root DLE. as well as various flags 
which are used by the GRFS file system to control access 
to the GRFS agent. The format of the GRFS agent 
advertisement structure is as follows: 
struct grfs_ws_adver_struct 

CHAR major_ver; 
CHAR minor_ver; 
CH2^ agent_type; 
CHAR flags; 

CHAR name [MAX_WORKSTATION_NAME_LBN'] ; 

GRFS agents use character representations of the 
values in the version and flags fields. For example, the 
major. minor version of a: particular GRFS agent might be 
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DATA BACKUP AND RESTORE SYSTEM FOR 
A COMPOTER NETWORK 

BACKGROU ND OF THR INVENTTnw 
Field of thP Tn vent.ion 

The present invention relates to a system for 
protecting data through backup and restore operations, 
and more particularly to backup and restore software for 
protecting data which is processed on a computer network 

Description of thP Relatgri art 

In order to ensure that original data stored on a 
medium such as a disk is not lost or dainaged, a copy of 
that data is stored on another medium. Should the 
original data be lost or damaged, then the copy may be 
accessed to reproduce the original data. This process of 
copying and reproducing is generally known as backup and 
restore. Typically, original data are stored on a hard 
or floppy disk of a computer disk drive and are backed up 
to and restored from tape media of a tape drive. 

Backup and restore of the data are simple in a 
system that has a single standalone computer, having a 
given operating system and one or more disk drives, that 
interfaces with a tape drive system. A relatively siit?>le 
backup and restore program can be used that interfaces 
with the computer operating system to backup data 
including files and directories stored on a hard disk to 
the tape drive and to restore such data from the tape 
drive onto the hard disk. 

Conputer networks have evolved and this has placed 
greater demands on backup and restore systems. a 
coit?)uter network may include a number of computers each 
with its own hard and/or floppy disk drive, all of which 
are networked together on a common bus. For example, the 
computers on the network may include one or more 
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"0043ONE_WOLF'' major version = 0 

minor version = 0 
Unix agent 
user name required 
password required 
DLE name = "ONE_WOLP" 

Fig. 4 illustrates a sequence of GRFS command and 
response messages in simplified form to backup data on 
the tape drive TD of the file sei-ver FS. This Fig. 4 
gives the example of backing up a 5000 byte file named 
C0MMaND.COM which is stored on a "DRIVEC of a given 
workstation named "DougCompaq" . it is assumed that the 
given workstation WS has advertised over the network 10 
sufficient information so that the GRPS file system can 
create the first command message shown in Fig. 4 as 
ATTACH_DLE(. 

To begin the 5000 byte backup, the workstation user 
will, via a given user interface 18, cause a display on 
a monitor M of devices and subdevices. The user will 
then select a given sxibdevice (e.g., DRIVEC in the 
example of Fig. , 4) , resulting in the user interface 
displaying on monitor M names of various files and 
directories. The user will then select the file name to 
be backed up (C0MMAND.COM in the example) resulting in 
the submission of a tape backup job for the file server 
FS in the network 10. 

Next, the sequence of GRFS file system command 
messages and GRPS agent response messages will occur as 
shown in order in the simplified Pig. 4. The sequence, 
as illustrated, commences with the GRFS command message 
ATTACH_DLE( naming "DougCompaq" (dle.id=oi) and completes 
with the final GRFS agent response message 
DETACH_DLE_STAT() by which DougCompaq (dle.id=01) is 
detached. Thus, the file C0MMAMD.COM will be read from 
DRIVEC and written onto the tape drive TD of the file 
server FS for network 10. 
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Obviously increases as more and more disparate operating 
systems are added to the network via the computers on 
which they run. 

In general, prior backup and restore systems for 
computer networks are limited to the number of different 
types of operating systems that can be supported. This 
places expansion limitations on the network in terms of 
adding computers running additional types of operating 
systems. Also, these backup and restore systems do not 
have the capability of interchanging data between 
different operating systems. Furthermore, bottlenecks 
occur and productivity is limited with prior backup and 
restore operations since multiple users cannot 
simultaneously request these operations. 

SUMMARY OF THE TISIVENTION 

The present invention provides a backup and restore 
system for use on a computer network having computers 
running disparate operating systems . Backup and restore 
software has modules including a backup engine 
containing, among other components, a generic remote file 
system (GRFS file system) and GRFS agents, being loadable 
on a computer network having a plurality of con^juters 
including, for example, at least one file server and at 
least one workstation. The GRFS file system may run on 
one coii5)uter, e.g., the file server of the network, and 
each GRFS agent may run on another conputer. e.g.. a 
workstation,^ on the network. The GRFS file system 
running on the one computer, i.e., the file server in 
this example, is allowed to access a file system of the 
other computer via the GRFS agent on that other conputer 
to backup and restore data on that computer. 

The GRFS file system and each GRFS agent Interface 
with one another over the computer network by a set of 
defined messages. This messaging system is based on a 
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is used by the backup application's tape format module 
and is written to the backup media of tape device TD. A 
well-known Microsoft Tape Format Version i.o 
Specification describes stream header structures and also 
contains a list of pre-defined stream header id values. 
The size field must be set to the number of bytes 
contained in the succeeding data stream and should only 
be set in the first stream header structure for a 
particular data stream, i.e., if the stream header id 
value is 0, then the size field does not need to be set. 

An exanqple is presented below of what a Macintosh 
GRFS agent would return in the GRFS_READ_OBJ_STAT 
messages when a file with a 2000 byte resource fork and 
a 4000 byte data fork is being backed up. This exan^le 
also assumes that a GRFS data buffer limit is 1000 bytes. 



B trm_header . id=srRM_MAC_RESOURCE 

strm_header .size=2000 

s t rm_header . id=STREAM_INVALID 

strm_header . size=0 
strm_header . id=STRM_NORMAL_DATA 
strm_header.size=2000 
strni_header . id=STREAM_INVALID 
St rnuheader . size= 0 
strm_header . id=STREAM_INVAIjID 
strm_header . size=0 
strm_header. id=STRBAM_INVALID 
st3:m_header . size=0 



(returns 
bytes o: 
fork) 



(returns 
bytes o: 
fork) 



1st 1000 
resource 



last 1000 
resource 



(returns 1st 1000 
bytes of data fork) 



(returns next IQOO 
bytes of data fork) 



(returns next lOOO 
bytes of data fork) 



(returns last 1000 
bytes of data fork) 
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DESCRIPT ION OF THE PREFERRED EMBODIMETJT.q 
Fig. 1 illustrates one example of a coir^uter network 
10 which stores, manipulates, and otherwise processes 
data. The network 10 has a niimber of computers 12 which 
can communicate with one another over a network bus 14. 
In the example of Pig. 1, the computers 12 include a file 
server PS and a plurality of workstations WS,, WS2, WS3, 
WS4, . . .WS„. Each of the workstations WS,-WS„ has a display 
monitor M and the workstations WS,-WS„ include hard disk 
drives HDD, -HDD,. The file server PS has its own large 
file server disk drive FSDD and a tape drive TD upon 
which to backup to and restore from data on the network 
10. 

Every workstation WS,-WS„ may be running the same 
operating system OS, or each workstation WS, through WS, 
may be running a disparate operating system, or there 
may be disparate groups of workstations with each group 
running the same operating system. For example, 
workstation WS, and workstation WSj may both be running 
the operating system known as DOS, workstation WS3 may be 
running the operating system known as OS/2, workstation 
WS4 may be running the operating system known as UNIX, 
workstation WS„ may be running the operating system known 
as Macintosh, and other workstations, not shown, or which 
may be added to the ^ network 10, may run the operating 
system known as Windows. Furthermore, the con^juters 12 
in the network 10 may be utilizing user interfaces such 
as those known as the DOS user interface, Windows 
graphical user interface, and a server-based NLM (NetWare 
Loadable Module) interface. 

The compter network 10 may be, for exanqple, running 
the operating system software known as NetWare 3.2 or 4.X 
which is produced by Novell, inc., of Provo, Utah. 
NetWare is designed to manage programs and data among the 
several computers 12 of the network 10. Fig. 1 also 
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alignment. The GRFS messages are defined with a "least 
common denominator" alignment that would apply to the 
above-noted major operating systems. Thus, for example, 
a given network 10 which may include workstations running 
5 only DOS, OS/2, and Macintosh, may be expanded to include 
a workstations nmning UNIX and/or Windows. In other 
words, the present invention supports a scalable network 
for backup and restore purposes from a small or 
departmental local area network (LAN) to a large or 

10 enterprise wide area network (WAN) . 

Furthermore, the message structure enables multiple 
users working at multiple computers 12 on the network 10 
to request simultaneously backup and restore of objects. 
This structure enables the GRFS file system to create a 

15 unique request id for every GRFS command message. 
Consequently, the GRFS file system can communicate 
simultaneously with multiple GRFS agents and, therefore, 
multiple users of the network 10 who at the same time 
want to have bac]cup and/ or restore operations performed. 

20 The present invention will manage these requests such 
that they are placed in a job queue in the file server 
FS, thereby allowing each user to operate independently 
from any other user on the network 10 and without waiting 
access to the backup and restore system. 

25 While each user can independently manage his/her own 

data on a given workstation, backup and restore of data 
on the entire network 10 can be centrally managed at a 
single location by, for example, a network administrator, 
from a given workstation or file server, or a system 

30 console. 

The remaining portion of this specification 
describes in much more detail the structure of the 
command/response messages, followed by a detailed 
description of the individual fields of the GRFS common 

35 
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having the corresponding operating system in order to 
access the file system of that given corr^juter. Thiis, for 
example, the DOS GRFS agent 20 will run on a DOS 
workstation WS, , the OS/2 GRFS agent will run on the OS/2 
workstation WS,, etc. The package 16 also has a backup 
engine 22 running on the file server FS and includes a 
tape controller device driver and tape positioner to 
control the mechanical operation of the tape drive TD, a 
common file system, and at least one device specific file 
system. The latter is a GRFS file system which 
interfaces with GRFS agents 20 via messages described in 
more detail below. 

Fig. 3 illustrates the network 10, but modified to 
include the software 16. As shown, the backup engine 22 
is installed at the file server FS, while the DOS, OS/2, 
UNIX, and Macintosh GRFS agents are installed on the 
respective workstations WSj-WSj, WSj, ws^, and ws„. in this 
example, the computer network lO does not have a coitputer 
12 running a Windows operating system. Should the 
network 10 be expanded to include a Windows workstation, 
then the Windows GRFS agent of the software 16 would be 
installed at that workstation. While not specifically 
illustrated, a workstation user also can opt to have 
installed one of the user interfaces 18 for tape backup 
and restore purposes, that is the same as that already on 
a workstation for other purposes . 

As indicated above, a GRFS agent is a program which 
runs on a network con^uter such as the given workstation 
WS, and which allows the GRFS file system running on 
another coitputer, such as the file server FS, to access 
the file system within the given GRFS agent's con?)uter. 
This access is accomplished by use of an interface 
between the GRFS file system and the given GRFS agent 
over the network bus 14. Specifically, the interface is 
defined by a set of GRFS messages which are documented in 
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SPECIFIC DESCRIPTION OF mV MAND/RRfiPnTJSE MESSAriRg 

3.0 Daing GRFS Command and Response Messages 

This following eections provide the information necessary to 
iinplement each of the GRFS conmand and response neasages. 

3.1 GRFS_ATTACH_DLE_, GRFS_ATTACH_DLB_STAT 

dle_naine: This field contains the name of the DLB that the 
^f'=l5^P.*PP^'^«^*tio« desires to attach to. The die name 
field as encrypted in conjunction with the encryption 
mf?h^° ^ ^^^1^°''^ ^"^^ ^« encryption/decryption 
method used by GRFS is described in the GRFS " 
encryptxon section of this document. 

bec.flags: ^s field contains a bit -mapped value -which defines 
the^ ccmf iguration options chosen by the backup 
th?= ^ot?* program The values defined for use in 
thxB field are as follows: 

BEC_BACKDP_FrLES_IHDSB 0x01 

If this flag is set, then the GRFS agent should 
attenqpt to <^en files even if they are already 
m use by another process. 

BEC_EXTEHDED_DATE_SnPPORT 0x02 

If this flag is set, then the backi^ application 
5?2?^^^°!'^*=°.'»«»dle the ACCBSS DATE and ARCHTffB 
DATE fields in the GRFS DBLK, so if the agent's 
OS platfoim supports these time-stairoB, they 
should be provided in OBUCs. 

BEC_SBT_ARCHrVB_FIAG 0x04 

If this flag is set and the agent's OS platform 
eupfiortB an cjbject "ARCHIVED" flag, then the 
GRFS agent should set an object's ARCHIVBD flag 
after the object is closed during the bacJcum 
operation. 

BBC_RESTORE_SECORITr 0x08 

If this flag is set and the agent's OS platform 
has support for security specific data forks (ie 
AOi BiflEjport for LAHMMI OS/2), then security 
information should be restored during the 
restore operation. 

BEC_GET_HIDDBM_PIX,ES OxlO 

T^is flag controls whether "hidden" objects 
returned while processing 
GRPS_PIND_F1RST_0BJ and GHFS_FIl©_HErr OTJ 
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retcode: This DINT16 field is used by GRFS status 

messages to hold the return code of the 
GRFS command. 

request_id: This UINT32 field contains a value which 
IS generated by the GRFS file system for 
GRFS command messages and must be returned 
unchanged in the corresponding GRFS 
response message. 

In the detailed description of the specific GRFS 
messages below under the heading "Specific Description of 
Command/Response Messages", the number of parameters 
associated with a given GRFS agent is assumed not to 
include the above GRFS common message header. The 
messages use two major structures to define GRFS objects. 
These two major GRFS object types are a drive list 
element (DLE) objects, which are logical devices, and 
file system objects, which are files and directories. 
The GRFS messages use DLE structures to reference drive 
list element objects and DBLK (descriptor block) 
structures to reference file system objects. 

A DLE is a structure that contains information about 
individual data storage devices which can be accessed for 
backup and restore. The DLE structure contains, the 
following types of information: logical device name, 
access password, file system delimiter, etc. 

A DLE structure also supports a hierarchical 
structure. A DLE can be a "pairent" DLE and can have 
"children" DLEs associated with it. For example, this is 
the case for a Novell server file system. For a Novell 
server, a DLE structure is created which is associated 
with the server and then DLEs for each volume on the 
server are created. The same situation can occur with a 
GRFS agent should that agent advertise or publish on the 
network 10 the workstation name as a DLE and then use 
children DLEs to advertise individual areas which can be 
accessed as logical units. 
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epecial_word : 
max_obj_b8ize : 



tjuipr_type : 
user name: 



This field is not used. 

This field contains the size of the buffer that 
the GRFS file system would like to use when 
transferring object data to/from the GRFS agent. 
This buffer aize is the size of the object data 
buffer, not the size of the GRFS message buffer. 
GRFS message buffers are larger than the object 
data buffer size because the GRFS message buffer 
must include the 8-byte common header as well as 
the miscellaneous parameters (obj_id, 
Btream_info, etc) used by the GRFS_NR1TE OBJ, 
GRFS_VBRIFy_OBJ, and GRFS_READ OBJ STAT 
messages . ~ 

The GRFS object buffer size is a negotiated 
size, so if the value contained in the 
niax_obj_bBize is larger than the agent would 
like, the agent can return a smaller value in 
the GRFS_ATEVCH_DI^_STAT max obj baize field. 
The GRFS file system will use the value returned 
by the GRFS agent if it is smaller than the 
default file system object data buffer size. 

This field contains the DI£ handle for the 
Pcurent of the DLB being attached to if a parent 
DIE exists. If a parent DLE does not exist, 
then this field is set to 0. 

This field is not currently supported. 

This field contains the user name supplied by 
the backup application. This field will be 
filled only if the DLK is defined as recjuiring 



password: This field contains the password supplied by 

back«9 application if che DLE is defined as 
requiring a password. Even if the OLS retires 
no password, this field will appear to have a 
value until it is decrypted. Please see the 
section on DLB name/Password decryption for more 
information. 

The proper response message for a GRPS_ArBVCH_DLE is the 
^S_ATTACH_DLE_STAT message. The parameters associated with the 
GRFS_DI.B_ATTACH_STAT message are described below. 

<ile_id: Hiis field must be set to the DIB id *rtiic±x the 

GRFS agent wishes to use to identify the DLE 
The DLB id is a 32 -bit value irtiicdi the backup 
e^lication will use in future GRFS commands to 
identify the DLB to be operated upon. 
Typically, the GRFS agent will create DLB ids as 
a pointer to a structure of an index into an 
array. The DLB id can be any value except 0. 

max_connectB : This field should be set to the maximum number 
of concurrent GRFS sessions which the agent is 
capable of. 
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data area is at most 1,024 bytes. Purtherroore, there are 
several fields within the DBLK structure, which are 
actually pointers to information within the DBLK data 
area. These pointers are generated as offsets from the 
beginning of the DBLK structure. For example, if the 
DBLK common area is 80 bytes long and the first item 
within the data area is the object's name, then the 
object name field would be set to 80 in order to point to 
the first byte following the DBLK common structure. The 
individual fields within the common DBLK structure that 
are manipulated by the GRFS agent programs are described 
in detail below under the heading "DBLK Fields". 

In order to implement a backup and restore function 
for a given computer 12, that computer 12 should 
advertise its capability for this purpose. Not every 
contputer 12 in the network 10 is necessarily running a 
GRFS agent program so as to be able to have its data 
backed up. Consequently, the GRFS agent programs will 
"advertise- their capability as a' GRFS agent over the 
network lo. This may be acconplished using the NRL 
resource advertisement function. The GRFS agent resource 
advertisement publishes the logical name of the 
particular agent's root DLE, as well as various flags 
which are used by the GRFS file system to control access 
to the GRFS agent. The format of the GRFS agent 
advertisement structure is as follows: 
struct grf s_ws_adver_struct 

CHAR major_ver; 
CHAR minor_ver; 
CHAR agent_type; 
CHAR flags; 

CHAR name [MaX_WORKSTATION_NAMB_LEN] ; 

GRFS agents use character representations of the 
values in the version and flags fields. For exarrple, the 
major. minor version of a particular GRFS agent might be 
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20 



25 



35 



40 



1.3, so that agent would advertise the version nmnbers as 
"1" and "3", respectively. 

The GRFS major version number is used to control 
which GRFS agents can be accessed by the GRFS file 
system. The GRFS major version number of the GRFS file 
system and the GRFS agent must match exactly or no 
information of the existence of that GRFS agent will be 
given. The GRFS minor version number may be used for 
informational purposes only. 

The agent_tyi>e field is used to define the type of 
GRFS agent. For example, the following values may be 
defined for this field: 

DOS 1 

0S2 2 

MACINTOSH 3 

UNIX 4 

The GRFS flags field is a bit-mapped value with the 
following flags currently defined: 
GRFS_WS_PASSWORD REQ 0x01 
GRPS_WS_USER_REQ 0x02 

Combining all the GRFS resource advertisement fields 
leads to the following examples of GRFS agent 
advertisements: 

NRL ResoiirrP Decoded a.c 



"1211RATB0Y_486" 



"1020SLEDGEHAMMER" 



major version = i 
minor version = 2 
DOS agent 

no user name required 

password required 

DLE name = "RATB0Y_486» 

major version =» i 
minor version = 0 
OS/2 agent 

no user name required 
no password required 
DLE name = 
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■•0043ONE_WOLF" major version - o 

minor version = o 
Unix agent 
user name required 
password required 
DLE name = "ONB_WOLF'' 

Fig. 4 illustrates a sequence of GRFS command and 
response messages in simplified form to backup data on 
the tape drive TD of the file server FS. This Fig. 4 
gives the example of backing up a 5000 byte file named 
C0MMAND.COM which is stored on a "DRIVEC" of a given 
workstation named "DougCompaq" . it is assumed that the 
given workstation ws has advertised over the network 10 
sufficient information so that the GRFS file system can 
create the first command message shown in Fig. 4 as 
ATTACH_DLE ( . 

TO begin the 5000 byte backup, the workstation user 
will, via a given user interface 18, cause a display on 
a monitor M of devices and subdevices. The user will 
then select a given subdevice (e.g., DRIVEC in the 
example of Pig. . 4) , resulting in the user interface 
displaying on monitor M names of various files and 
directories. The user will then select the file name to 
be backed up {C0MMAND.COM in the exan^Jle) resulting in 
the submission of a tape backup job for the file server 
FS in the network 10. 

Next, the sequence of GRFS file system command 
messages and GRFS agent response messages will occur as 
Shown in order in the simplified Fig. 4. The sequence, 
as illustrated, commences with the GRFS command message 
ATrACH_DLB( naming "DougCompaq- (dle.id^Ol) and completes 
with the final GRFS agent response message 
DETACH_DLE_STAT{) by which DougCompaq (dle.id=01) is 
detached. Thus, the file C0MMAND.COM will be read from 
DRIVEC and written onto the tape drive TD of the file 
server FS for network 10. 
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Fig. 5 shows a sequence of GRFS command/ response 
messages to restore information backed up on the file 
server FS of the network 10. In this example, it is 
assumed that a 5000 byte file named CONFIG.SYS has been 
5 backed up from a given workstation and is to be restored 
to DRIVEC of the workstation DougCompaq. After the 
workstation user has selected the file CONFIG.SYS using 
the user interface to select the file CONFIG.SYS for 
restore, the sequence of GRFS command/response messages 
10 will proceed as shown in Fig. 5. The sequence begins 
with the GRFS command message ATTACH_DLE ( and completes 
with the GRFS response message DETACH_DLE_STAT ( ) The 
file CONFIG.SYS will be read from the tape drive TD and 
restored onto DRlVEC. 
15 As mentioned previously, the command/ response 

messages are structured such that objects such as files 
and directories may be backed up from a GRFS agent 
running one operating system, e.g., OS/2, and restored to 
a GRFS agent running another operating system, e.g.. DOS. 
20 This is accon^lished by the messages containing a 
structure GRFS_STREAM_INFO . This structure has the 
following definition: 

struct GRFS_STREAM_INFO ( 
UNET32 id- 
UNET16 fslattrib; 
UNET16 tf.attrib; 
UNET64 size; 

When the backup application is reading an object 
the GRFS_READ_OBJ_STAT response message contains a 
GRFS_Sll^_INFo structure. The GRFS agent program must 
set the id field of the first GRFS_READ_OBJ_STAT response 
message of each individual data stream to the appropriate 
value for the agent's particular operating system 
Succeeding GRFS_READ_OBJ_STAT messages for the stream 
must have the stream header id field set to o 
(S-niEAJt.INVALID) . The data in the stream info structure 
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is used by the backup application's tape format module 
and is written to the backup media of tape device TD. A 
well-known Microsoft Tape Format Version i.o 
Specification describes stream header structures and also 
contains a list of pre-defined stream header id values. 
The sise field must be set to the number of bytes 
contained in the succeeding data stream and should only 
be set in the first stream header structure for a 
particular data stream, i.e., if the stream header id 
value is 0, then the size field does not need to be set. 

An example is presented below of what a Macintosh 
GRFS agent would return in the GRFS_read_OBJ_STAT 
messages when a file with a 2000 byte resource fork and 
a 4000 byte data fork is being backed up. This example 
also assumes that a GRFS data buffer limit is 1000 bytes. 



strm_header . id=STRM_MAC_RESOURCE 



20 strm_header 
strm_header. 



strm_header 
stnn_header 
strm_header 
strm_header 
stnri_header 
strm_header. 
strm_header. 
strm_header, 
strin_header. 



size=2000 
id=STREAM_INVALID 

. size=0 

. id=STRM_NORjMAL_DATA 

.size=2000 

. id=STREAM_INVALID 

.size=>0 

, id=STREAIl.INVALID 
size=0 

id=STREAM_INVALID 
size=0 



(returns 1st 1000 
bytes of resource 
fork) 



(returns last lOOQ 
bytes of resource 
fork) 



(returns 1st 1000 
bytes of data fork) 

(returns next lOOO 
bytes of data fork) 



(returns next lOOO 
bytes of data fork) 



(returns last lOOO 
bytes of data fork) 
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When the backup application is restoring an object, 
the GRFS comrnands (GRFS_WRITE_OBJ, GRFS_VER1FY„0BJ) will 
also contain a GRFS_STREAM_INFO structure. The GRFS 
agent must examine the stream header id value to 
determine whether the data stream type is supported on 
the agent's operating system platform. if the data 
stream type is not supported the GRFS agent should set 
the response message retcode to FS_DONT_WaNT_STREAM. 
This will cause the backup application to skip to the 
next data stream or the next object if at the last data 
stream for a particular object. For instance, if an 
object was backed up from an OS/2 agent which supports a 
normal data stream, an extended attribute (EA) data 
stream, and an access control list (ACL) data stream, 
then if the object is restored to a DOS agent, the DOS 
agent will return FS_DONT_WANT_STREAM when it receives ' 
GRFS_WRITE_0BJ commands with stream header , id values that 
indicate either EA or ACL data streams are being restored 
since this data is not supported by DOS. The DOS agent 
will accept the normal data stream which it does support. 
Thus, this functionality allows objects to be backed up 
from an agent running on one operating system and 
restored to an agent running on another operating system. 

As also mentioned above, the message structure is 
defined as well, such that backup and restore can be 
supported with respect to most operating systems, 
including the current major operating systems which are 
DOS, OS/2, Ijacintosh. Windows, and DNIX. Bach operating 
system will have its own data structures aligned 
differently from one another. For example, one operating 
system may have a 1-byte alignment where a data byte may 
be placed anywhere, whereas another operating system may 
have a 2-byte alignment where a data byte may be placed 
in either an even or odd byte location. Other operating 
systems, for example, may have what is known as a 4 -byte 
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alignment. The GRFS messages are defined with a "least 
common denominator" alignment that would apply to the 
above -noted major operating systems. Thus, for example, 
a given network 10 which may include workstations running 
only DOS, OS/2, and Macintosh, may be expanded to include 
a workstations running UNIX and/or Vfindows. In other 
words, the present invention supports a scalable network 
for backup and restore purposes from a small or 
departmental local area network (LAN) to a large or 
enterprise wide area network (WAN) . 

Furthermore, the message structure enables multiple 
users working at multiple computers 12 on the network 10 
to request simultaneously backup and restore of objects. 
This structure enables the GRFS file system to create a 
unique request id for every GRFS command message. 
Consequently, the GRFS file system can communicate 
simultaneously with multiple GRFS agents and, therefore, 
multiple users of the network 10 who at the same time 
want to have backup and/or restore operations performed. 
The present invention will manage these requests such 
that they are placed in a job queue in the file server 
FS, thereby allowing each user to operate independently 
from any other user on the network 10 and without waiting 
access to the backup and restore system. 

While each user can independently manage his/her own 
data on a given workstation, backup and restore of data 
on the entire network 10 can be centrally managed at a 
single location by, for example, a network administrator, 
from a given workstation or file server, or a system 
console. 

The remaining portion of this specification 
describes in much more detail the structure of the 
command/response messages, followed by a detailed 
description of the individual fields of the GRFS common 
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DBLK Structure which may be manipulated by GRFS agent 
programs - 
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SPECIFIC DESCRIPTION DF COMMAND /PE SPONfiB Nres.qartTCC! 
3-0 Using GRFS Command and Reeponse Hessagee 

This following sections provide the information neceeeary to 
implement each of the 6RPS command and response messages. 

3.1 GRFS_ATTACH_DLE_, GRPS_ATrACH_DLE_STAT 

After eetabliehing an MSI, sesBion vith the GRFS agent, the first 
^^^DSr^.^^r,^'*"^ application will send to the GR^s agent !s 
eo^t-«?^!-^r^5"T?^ GRFS_ATTACH_DLS command message 
contains the following parameters: ' 

dle_naine: This field contains the name of the DLE that the 
backup application desires to attach to. The die name 
field 18 encrypted in conjunction with the encryption 
done on the password field. The encryption/decryption 
method used by GRFS is described in the GRFS 
encryption section of this document. 

bec.flags: This field contains a bit -mapped value which defines 
the configuration options chosen by the backup 
application program. The values defined for use in 
this field are as follows: 

BEC_BACKDP_PILBS_IHnSB 0x01 

If this flag is set, then the GRFS agent should 
attenqpt to open files even if they are already 
in use by another process. 

BEC_EXTEHDED_DATE_snPPORT 0x02 

If this flag is set, then the backup application 
knows how to handle the ACCESS DATE <md ARCHIVE 
DATE fields in the GRFS DBLK, bo if the agent' s 
OS platform supports these time- stamps, they 
should be provided in DBLKs. 

BEC_SET_ARCHIVB_PIAQ 0x04 

If this flag is set and the agent's OS platform 
si^jporte an object "ARCHIVBD" flag, then the 
GRFS agent should set an object's ARCKXVBO flag 
after the object is closed during the backup 
operation . " 

BBC_RESTORE_SECDRITY 0x08 

If this flag is set and the agent's OS platform 
has support for security specific data forks (ie 
ACa support for LANMAN OS/2), then security 
information should be restored during the 
restore operation. 

BBC_GET_HIDDEN_FII,ES OxlO 

This flag controls whether "hidden" objects 
should be returned while processing 
GIlFS_FIND_FIRST_OBJ and GRPS_Flin)_NEZT_OBJ 
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BBC_GBT_SYSTKK_FILES 0x20 

Thia flag controls whether "Byatera" objects 
should be returned \*ile processing 
GRFS_FI»D_FIRST_OBJ and GRFS_FIND NEXT OBJ 
coxmnands . ~ 

BBC_PROC_BMPTy_DIRS 0x40 

This flag controls whether directories which are 
exujty should be returned while processing 
GRFS_FIHD_FIRST_OBJ and GRFS_FiMD NEXT OBJ 
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special_vor(i: This field is not used. 

«>ax_obj_bsize : This field containe the size of the buffer that 
the GRFS file Bystem would like to use when 
transferring object data to/from the GRFS agent . 
This biiffer size is the size of the object data 
buffer, not the size of the GRFS message buffer. 
GRFS message buffers are larger than the object 
data buffer size because the GRFS message bxif fer 
nniBt include the 8-byte common header as well as 
the miscellaneous parameters (obj_id, 
6tream_lnfo, etc) used by the GRFS_WR1TE OBJ, 
GRFS_VERIFy_OBJ, and GRFS READ OBJ STAT 
nessageB . ~ ~ 

The GRFS object buffer size is a negotiated 
size, so if the value contained in the 
n>ax_obj_bBize is larger than the agent would 
like, the agent can return a smaller value in 
the GRFS_ATTACH_DLB_STAT max_obj_bBi2e field. 
The GRFS file system will use the value returned 
by the GRFS agent if it is smaller than the 
default file system object data buffer size. 

dle_parent: This field contains the Dli handle for the 

parent of the DI^ being attached to if a parent 
DLE exists. If a parent DLE does not exist, 
then this field is set to 0. 

c«q?r_type: This field is not currently supported. 

user_naffle: This field contains the user name supplied by 

the baclciq) application. This field will be 
filled only if the DLE is defined as requiring 
a user name. 

password: This field contains the password sv^jplied by 

badcup application if the DLE is defined as 
requiring a password. Even if the DLB requires 
no pasBvrord, this field will appear to have a 
value until it is decrypted. Pleaae see the 
sectioo on DLB name/Password decryption for more 
information. 

The proper response message for a GRPS_ATTACH_DI.B is the 
QRPS_ATTACH_DI.E_SXRT message. The parameters associated with the 
GRPS_DLB_ATTACH_STAT message are described below. 

dle_id: This field must be set to the OLS id «^ich the 

GRFS agent wishes to use to identify the DLB. 
The DLB id is a 32 -bit value which the h&ckxxp 
application will use in future GRFS cooBnands to 
identify the DIB to be operated u^jon. 
Typically, the GRFS agent will create DLB ids as 
a pointer to a structure of an index into an 
array. The DLB id can be any value except 0. 



nax_connect6 : 



This field should be set to the maximum number 
of concurrent GRFS sessions which the agent is 
capable of. 



SUBSTITUTE SHEET (RULE 2B) 

BMSDCCID: .cWO 95t35aOAl . 1. > 



wo 95/13580 



PCTaJS94/n915 



max_opens_per_connect: This field should be eet to the sa«.nium 
number of objects which can be opened 
sinvultaneouBly per GRFS session. 

process-ddbs: This field is not currently supported. 

niax_obj_b8ize: This field should be eet to the maximum object 
data buffer size the agent wishes to use. The 
maximum GRPS message size is greater than the 
maximum object data buffer size because of the 
additional parameters in the GRFS meBsages which 
convey object data. 

cn5)r_type: This field is not currently supported. 

supportB_children: This field is a BOOLEAN flag which should 

be set to 0 if the DLE does not support 
children. A non-sero value declares the 
DLE as supporting children DLBb. a DUB ■ 
declared as si^porting children DLEs 
CANNOT support file system objects as 
well. Eitjier a DLE supports children 
DLEs or file system objects.' Never both. 

path_len: This field should be set to the length of the 

string (including the '/O' terminator) returned 
an the current_path field. Current GRFS agent 
aaplementations will always start in the logical 
root directory of DLEs when they are attached 
BO the current_path field should always be set 
to and the path_len field set to l. 

current_path: Tfais field should be set to the current path of 

the DLB being attached to. As described above, 
at DLB attachaient time, the current path will be 
the logical root of the DLE, so the current path 
IB enpty (•*) . 
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3.2 

GRFS_FIND__FIRST_DLE, GRFS_FmD_NBXT_DIiB , GRFS_FIND_DLK_STAT 

2*^.?^!-"^-^^^-°^ GRFS_FIND_NEXT_DLE connnands are used 

mij= application program to enumerate children DLKs for 

DLEB which are declared as supporting children dles. The sole 
parameter associated with these two commands is the dllid 
parameter. The backup application will supply the die id value 
was previously returned by a GRFS ATTACH DLE STAT~response 
message. The GRPS agent ahould respond with a GRFS~FIND DLE STRT 
message to both the GRFS_PIND_FIRST_DLE and GRFS-piHD-HKT 



It le the responsibility of the GRFS agent to detennine the 
sequence and keep track of the children DLEs as they are being 
enumerated. The parameter in the GRFS FIND DLE STAT response 
message are described below. " - - response 

dle_name: This field should contain the name of DLE which is 
Btring*'*""^"*'^''' "^alue «uBt be a null -terminated 

path_delim: Thie field should contain the ASCII code of the 
character used by the agent's file system. 

paBBwd_req: -miB field is a boolean flag and should be set to 0 if 
no password is required to attach to the die. a non- " 
sero value in this field indicates that a password is 
required . 

U8er_req: This field is a boolean flag and should be set to 0 if 
no user name is required to attach to the DLE. A non- 
zero value m this field indicates that a user name is 
required in order to attach to the DLB. 

dle_writable : 

This field is a boolean flag used to indicate whether 
restore operations are permitted on the DLE. Setting 
this value to 0 will prevent the backi^ applicatim 
from attempting restore c^Jerations. 

laBt_acceBB_aiflpported : 

T^^^i^^*^}^-, * ^^^^ used to indicate whether 

the DLB's file system 8»^orts the last access date 
information. This field is used toy the Backup 
«>plication to determine whether file- grooming is 
siqjported for this device. »^"v«u^a 



OB_ver: 
fB_type: 



This field is not currently used. 
This field is not currently used. 

This field is a boolean flag and should be used by 
ops agents to indicate that the DLB being returned is 
tne last child DLB available. if the GRFS agent is 
incapable of knowing ahead of time whether this is the 
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last DLE then this field can always be set to a non- 

application to sent GRFS_FIHD_mext_DLE commandB until 
the GRPS agent responds vith a FS_NO_MORB return code . 
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3-3 GRFS_DETACH_DLE, GRFS_DETACH_DLE_STAT 

The GRFS_DETACH_DLE command is used by the backup application «hen 
it no longer needs to access a DLE. The message has only one 
command epecxf ic parameter, the dle_id of the DLB irtiich the backup 
application wishes to detach from. DLEs will always be detached 
in the Jfeverse order to which they were attached. In other words 
^} attached to will be the first to be 

detached from. When a DLK is detached, the GRFS agent can free 
associated with the attached DLB. The 

^S^fcSiSSzSii-SLnr"^^^ ^ SJI 
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3.4 

GRFS_FIRD_FIRST_OBJ, GRFS_FIND_NEXT_OB J , and GRFS_FIND_OBJ_STAT 

The backup application uses the GRFS find first obj command to 
begin scannxng for file system object^. GRFS aiente must take 

»?r^«^ GR^S ATTACH_DLB comnand. These flags specify whether 
?Sc^L.^^"* ^^^"^ objects should be ^tu^ed for 
GRFS_FIND_FIRSr_OBJ and GRFS_PIiro_KEXT OBJ connnands ThI 
parameters associated with find first cononSnd are essplaiaed below 



find_type: This field contains one of these values: 

0x00 -return all object types found 

0x01 -return only directory objects found 

sname: This field containB the search string qualifier 

Normally this field will contain the string-* »- 
Btrxng means that all objects that meet the 

find_type criteria should be returned. 

3.4.1 GRFS Agent Path Generation 

When a GRFS agent is creating the path string used for its file 
system's -FindFirst" system call, the following cS^ents^S^Bt 
^al^'^f.H^.K'^t^* the correct path string, -melplth striS mus? 
begxn with the base directory of the DLB. The DI^s current Mth 

ifi-K^S^*'* ^° P*"* string. The GRFS agent must also supply 
path delxmetere wherever required. An e«4>le of a -PindP^st^ 
path string created by the OS/2 GRFS agenrTI presented telcJiJ^ 

DLB base path: "C:\DOCS* 

DLB current path: "GRFS\DBSI(3H" 

The GRFS agent creates the path string: -C:\DOCS\GRFS\DBSXGM\*. 

^'^^L^LIt^^^^^^ track of ,fl,en path delimeters 

^t ^r^ro^''!;^^ GRFS agent publishes the 

fSllo,^ ^ P*"* string is created as 



DLB base i>ath: "C:\» 

DLB current path: "DOCSVCRFSNDBSIGM" 

GRFS agent creates the path string: "C:\DOCS\GRFS\DESIGN\*.»« 

^t^^^ agent does not insert a path delimeter after the DLB base 
path because the DLB base path already ends with a path delimeter! 

3.4.2 GRFS Find Info Area 

One of the most important fields in the GRFS DBLK data area is the 
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Find Info area. Operating systems usually require some data which 
was returned from a FindFirst operation in order to perform 
subsequent PandNext operations. GRPS is designed so that the Find 
Info will reside in the GRFS DBLK, and the Find Info will be 
available to the GRFS agent whenever the GRFS FIND NEXT OBJ 
conimand is issued. This is accon?>li8hed by pasiing "the DBLK 
containing the Find Info back and forth between the backup 
application and the GRFS agent. 
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The backup application will never modify the Find Info data area. 
The GRFS_PIND_NEXT_OBJ message has only two parameters: 

'^jiiit^^ contains the id of the DLE that the backup 
application wishes to continue scanning. 

•^^^^'^i^ * "^^^^^ contains the Find Info «iata 

Station. ^^^"^^ perform a PindNext 

The 6RPS agent must respond with a GRFS FIND OBJ STAT reroonse 
mess^e to both the GRFS_Fim>_FIRST_OBJ and the G^S-^iS ^^BJ 
^Sld belST: "'•^^''^ response- meslage -are 

more.flag: ^= field contains a boolean value that can be used 
^J^l indicate to the GRPS file system 

Z]^^^t are any more objects available after the 

^I L T^t^^T returned. If the more flag, is 

f^^i *^°.? (FALSE), then the next time the" backup 
a FincaNextObject function call,^ 
, , ^^^^ ^'ill immediately return FS HO WJRB 
«tt.- ^ transmit GRFS_FIKD NEXT OBJ cc»mHd to 

"^l*" »»eing returned ie the last 
"l^ *9ent can always set this 
^o^o * non-zero (TRDB) value. This will force the 
»^^.5*" <?«Sr^'^ '° * GHFS_FIIID NEXT OBJ command 

Md^the GRFS agent to respond wi'th a PS.MOImORE return 

"^UJ^^^^^ -^^^^ complete GRFS DBLK. If a 
direetozy^3ect xs being returned^ then the directorv 
name should be a full path relati;re to the SIb^m 
^oll'/srl^^'^IllJ^ .current path of a DLE is 
-^ibi-^I; IS returning the directory 

TRACB , then the path returned in the DBLK data area 
h""^!^!^^™*^"- The pa^^t^ nS!! 
in^?i^S^?; the null -terminator character must be 
included in the path length field in the DBLK ccomon 
I^oaS*;™'^V^?^'^"°^ **3ects are retuSed^ 
the path name '\0' and the path-leng field set to 1. 

lillJ^J^^J^%^ returned as null- terminated 

strings, but only the actual file name is returned. 
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3.5 GRFS_FIND_CLOSE and GRFS_FIMD_CLOSB_STAT 

The GRFS_PIIID_CL0SE camnand is used by the backup application when 
It is done scanning a particular directory. When a GRFS aqent 
receives a GRPS_FIND_CLOSB message, the agent is allowed to 
release any resources associated with the 
S^f two ;fraB.eters in "Si 

GRFS_KlND_CLOSE message and they are described below: 

dle_id: 

dblk: 

The proper re^onse message type for the GRFS_F1MD CLOSE command 
xs the GRFS^FIMD_CLOSB_STAT message. There are "no parameters 
associated with the GRFS FIND CLOSE message. 



BNSDOCin <WO_9S13580A1J_> 



SUBSTITUTE SHEET (RULE 26) 



PCT/US94/12915 



3.6 GRPS_GET_OBJ_INFO, GRFS_GBT_0BJ_1NF0_STAT 

The GRPS_GBT_OBJ_INFO command is used by the backup application to 
retrieve a completed DBUC when the backup application has only a 
partially complete DBLK. The only DBLK fields which are required 

message is the fully conpleted DBLK. 

^ Blight difference between how a DBLK ia created for 
GRP^^GET^OBJ.IHFO command. All other GRFS co«maa«ta whilh 
create DBLKa return a fully specified path as the object name f ^ 
directory objectB. The GRFS_GET_0BJ_IIIFO_STAr DBLK returns OHLY 
tje^directory name as the path data in the DBLK data area. This 

**** If the DBLK sent to the agent contains a Find Info area 
then the agent MOST preserve this data within the DBLK which 
IS returned to the backup application. 
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3.7 GHFS_GET_COHRE»T_DDB, GRFS_GET_CURRBNT_DDB_STAT 

The GRFS^GET_CURRBNT_DDB command Ib used by the backup application 
^.^^^^i.^"^® * correBponding to the DLBe current directory 

path The proper response neseage type is GRPS GET OBJ info STAT 
^L?^?^®i^°^r P^^** string returned in the DBLK liCiBt "be a'fully 
Ssented blw^^''^ '° ^ "^^^ P***' e^le is 

DLE'B base path: "C:\OS2" 
CLE's current path: "WlHOS2\sySTEM" 

returned in the DBLK data area would be 
^^f?^^^P^ • ^ ^'^^^ °^ ^"e'^t path b^ing tSI 

logical root directory as presented below: 

CLE's base path: "C:\OS2" 

DLE'B current path: •* 

^o' ^^^^ ^^^^^^ "^"^ returned in the DBLK data area would be a 
'\0' and the b.d.os_path_leng field would be set to 1. 

•**• Whenever a GRFS agent returns a logical root director/ 

'^^n^^^S ' ^'^^ should be let w 

'\0' and the b.d.os_path_leng field should be i. 
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3-8 GRFS_CRKATE_OBJ, GRFS_CRKATE_OBJ_STAT 

'^t,^^-^J^'^-°^^ command ie used by the backup application 
during restore operations in order to create a file syst^ obiecT 
The parameters associated with this command are the following: 

dle_id: This parameter contains the DLB handle of the DLB 
where the object should be created. 

dblk: ^8 parameter is a aamplete DBLK and contains the 

type and the name of the object to be created. 

Directory object DBLKs will contain fully specified paths, so the 
DLB 'B current path is NOT included when treating the full pf?hol 
the object to be created, GRFS Agents must be cLable of «eatina 
^ic™^n^°* ^ specified directory paSTfroS a iSSf 

GRFS CRKATB OBJ command. Pnr- «»=mr,i=, C-iL_ "rr__?^ 



GPPS OREATB.OBa command. -yor^^r^r^^rLS^' 
?r?h^a^r^^»,'"'i^*^l* directory -WI101\TORD\DOCS\ISPBCSV 
If the any of the directories "DOCS", "WORD", or "WHni" do not 

directories within the fully specified path. ^vm-^s 

dirlctSj!'^^ ^^'^^^ created in the DLB ' s • current path 

The proper response message type is GRFS CREATE OBJ STAT. There 
are no parameters associated with this response Inessage 
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3.9 GRFS_OPEN_OBJ, GRFS_OPEN_OBJ_STAT 

~^ri^*!!^/^^^^^**A°'' * file Byetem object before any 

read, write or verify operations can be performed on the obiect 
^^.S^ld^tel^:'*" ''ith the GRFS_OPEN_oTa SlS'd are 

dle_id: This field contains the DLE handle of the DLB where 
the object to be opened resides. 

mode: This field contains a flag value which is GRFS agent 

must use to determine the mode which should be used to 
open the object. This value will be one of the 
rol lowing: 

0 REM) mode (backup operation) 

1 WRITE mode (restore operation) 

2 VERIFY mode (eoirpare c^ration) 

JJjif f^^''^'' " 5 complete DBLK and contains the 
type and the name of the object to be opened. 

When a backup application is backing up a GRFS aqent the baekun 
^e G^r^.°Tr ^icb a;e alrea'dy^n S^f ^ 

w ^^J. ^^^^J machine. The BBC_BACKDP_PILBS INDSE flag in the 
?H ^'■^^^ °^ GRFS JVTTACH_DLB coSnand determines lAethe^ 

^^.^^^f** ^ * different process, if the DiB is coaf igured w 

When an object is opened successfully, two parameters are returned 
i« response message": fir^? pCS^lJ 

« parameter is a 32.bit value generated by^e 

5^ ^Iw"" P^Sect handle. All succeeding GRFS co^nands 
V^J^^^'^ reference the obj id. As ^^^^ 

Sate^Se<i?it1^5re?^.^^ ^^^^^^ desired °S 

A completed DBLK is also returned to the backu© application in the 
S^^^n*^"*'^/,. "^-^^ agent's pperatinrw^^Tla^S 

^L^a^^Jf^^^^"" attributes which arl ^ssibfe^S 

after the object has been sueeesBfully opened, they can be aaved 

S St^e" ^ "lc«gna«es» are accessible only after the^cl 
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3-XO GRFS_READ_OBJ, GRFS_RKAD_OBJ_STAT 

The backup application uses the GRFS RKWD_OB J command to read data 
from previously opened file system objects. The parameters 
associated with this command are described below: 

obj_id: This field contains the object handle id which was 
returned by the agent in the GRFS OPEN OBJ STAT 
response message. ~ ~ 

size: This field contains the sise (inSpl230XbyteB) buffer 
which is available to receive data. The GRFS agent 
should endeavor to return as much data as possible for 
each GRPS_RRAD_OBJ cos -= 



offset: This field contains the number of bytes offset into 
the object the agent should begin ret%aming data from. 

The proper response message type is GRFS READ OBJ STAT. The 
response message has four fields which are descriied "below: 

size: This field should contain the actual number of bytes 

of data being returned in the response message. 

blk_Bize: This field should usually be set to 1. This field is 
used by GRFS agents to request a specific number of 
bytes to be read by the next GRFS READ OBJ commcmd. 
This functionality can be used if certain data areas 
must be read as "atomic" objects. 

As an exan?>le, suppose the backijp application requests 
to read 20 bytes. The GRFS agent has 14 bytes 
available, and then the next 12 bytes must be read a 
unit. The GRFS worad return the 14 bytes, set the 
size field to 14, and set the blfc_size field to 12. 
This will force the back»^ application to request 12 
bytes in the next GRFS_RBAD OBJ r 



The GRFS agent must never set the blk size field 
larger than the negotiated GRFS maximum object buffer 
aise. 

This field is a STRBJas_lHFO structure and is discussed 
in section 1.3 of this document. 

This field is the buffer i^ch contains the actual 
data. The size of this buffer is limited to the 
maximxim object buffer size as negotiated during the 
DiB attach operation. 



BNSOOCID: <WO_9£135eoA1J > 
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3.11 GRFS_WRITE_OBJ, GRFS_WRITE_OBJ_STAT 

The backup application uses the GRFS_WRITE_0BJ command to restore 
data to a GRFS agent . The parameters associated with this conmand 
are described below: 

obj_id: This field contains the object handle id which was 

returned by the agent in the. GRFS_OPEN OBJ STAT 
response message. 

size: This field contains the size (in bytes) of the data 

biiffer which is to be written. 

offset: This field contains the offset in bytes, from the 

beginning of the object, that the GRFS agent should 
begin writing the data biaffer. 

stnn_info: This field contains a STHKAM_INPO structure. As 
described for the GRPS_RBW>_0BJ response message, the 
first block of each data streasoi will have the ' 
stzin_info.id field set to the stream data type. All 
succeeding blocks of that data stream type will have 
the strm_info.id field eet to STRM_INVALId . The first 
block of a particular stream data type will have the 
Btnn_info.si2e field set to the total size (in bytes) 
of the stream. 

GRFS agents should ignore a data block for a stream 
type that they do not recognize, and their response 
message should indicate that the entire block was 
successfully written. 



The prefer response message type is GRFS_MRITE OBJ STAT. This 
response message heis the following parameters associated with it: 

size: -mis field should be set to the number of bytes 

successfully written. 

blk_size: This field should normally be set to 1. This field ie 
used to indicate that the GRFS agent requires a 
specific number of bytes to be written in the next 
GHPS_WRITB_<»J command. Any value other than X will 
force the backup application to attempt to write the 
requested number of bytes during the next 
GKFS_WR1TB_0BJ operation. The agent should NEVER set 
this field to greater than the negotiated maximum 
object buffer size. 



BNSOOCID: <WO_9513580A1J_> 
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3.12 GRFS_VERIFY_OBJ, GRFS_VERIFy_OBJ_STAT 

The backup application usee the GRFS VERIFY OBJ ccjmmand to verifv 

Se^es^T^d lelow: P^^^'^^" associated with this connnani 

obj_id: This field containe the object handle id which was 

returned by the agent in the GRPS OPEN OBJ STAT 
response meseage. ~ 



Bi*e: This field containe the size (in bytes) of the data 

buffer which is to be compared. 

offset: This field contains the offset in bytes, from the 
beginning of the object, that the GRFS agent should 
begin coB?>aring the data buffer. 

stnn_info: This field contains a STREAMLINFO structure and is 
described in section 1.3 of this document. 

3St it'io "^ritHi^ '^^"^^^^ 

^S^f?®"^ response message type is GRFS VERIFY OBJ STAT. This 
response message has the following paramerers assbciated with i" 

"^UJf^^i ^^""^f. ^ ^^•^ '^""fer of bytes 

successfully verified. j •.=>•» 

blk_size: Should normally be set to 1. This field is 

used to indicate that the GRFS agent reouires a 
riirfriSrSr^:?'^ °^ ^ verified i^^e nex? 

f^iz^^^ command. Any value other than X wiU 
application to attempt to verify the 

OBJ operation. The agent should NEVER set this field 
to greater than the negotiated maximum object buffer 
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3-13 GRPS_SEEK_OBJ, GRFS_SEEK_OBJ_STAT 

The backup application uses the GRFS_SEEK_OBJ command to force the 
GRFS agent to move the previously opened object's file location 
pointer to a specific offset within the object. This command ie 
typically used ^ the backup application to seek past sectors 
which are unreadable in ht>pes that some of the data may be 
readable (HaHa) . The parameters associated with this command are 
described below: 

obj_id: This field contains the object handle id- which was 
returned by the agent in the GRFS OPEN OBJ STAT 
response message . — — _ 

offset: This field contains the offset in bytes, from the 
beginning of the object, that the GRFS agent should 
move the file pointer to. 

The proper response mesBage type is GRPS_SBEK_OBJ STAT TliiB 
response message contains only one parameter associated with it 
■me parMieter, 8eek_obj_offset specifies the offset within the 
object that the agent was able to seek to 
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3.14 GRFS_CLOSE_OBJ, GRFS_CLOSE_OBJ_STAT 

^® application uses the GRFS_CLOSK OBJ command to force 

toe GRFS agent to close a previously opened file syatem object 
When an object is closed, the agent is allowed to free 
resources associated with the open object. The only parameter^ 

this command mennaao -ia <-V» ^■k.^ ,m-j_ J! • ^ ""'ci-ci J.U 



H=„i-i ^i^l'i- This field contains the 

«r,™^^® returned by this agent in the 

GRFS_OPEN_OBJ_STAT response message. 3 t in iine 

The proper response message type is GRFS CLOSE OBJ STAT There 
are no parameters with this ~— — - ■'"^re 



response message. 
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3.15 GRFS_DELETE_OBJ, GRFS_DKLETK_OBJ_STAT 

The GRFS_DBl.BTB_OBJ command ia weed by the backup application 
during transfer operations in order to remove a file system 
object. The parameters associated with this command are the 
following: 

<31e_id: This parameter contains the DliE handle of the CLE 

where the object should be removed. 

dblk: This parameter is a complete DBLK, and contains the 

type and the name of the object to be deleted. 

*p905Xfully Directory object DBLKe will contain specified paths, 
so the DhB'e current path is NOT included when 
creating the full path of the object to be deleted. 

backup application will first remove file objects 
from a directory object before removing the directory 
object. 

File objects are always deleted from the DLB'a current 
path directory. 

The proper response message type is 
caiFS_DBi:.ETE_OBJ_STAr. There are no parameters 
associated with this response message. 
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3.16 GRFS_CHANGE_D1R, GRFS_CHANGE_DIR_STAT 

The GIIPS_CHANGE_DIR command is used by the backup application to 
^J:^^ ^^^^^ ^° «=^9e the "current directory" of a specific 
path supplied in the meBsage is always a fully 
specified path relative to the DLB'b base path. The GRFS agent 
HOST verify that the new path is a valid path. This can usulljy 
be accoBplxshed ^ performing a "PindFirst" operation on the new 
path. As Ml added bonus, the baeJciqs application may send a "null- 
impreguated« string in the path field. Tliia means that the GRFS 
agent must replace the internal '\0' path delimeters with the 
nfcessLy P*'^ delimeter character. No applause 

The proper response message type is GRPS CHANGE DIR STAT. There 
are no parameters associated with this response "iaessaqe . 
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3. 18 



GRFS_SET_OB J_1IIF0 . GRFS_SET_OB J_INFO_STAT 



The GRFS_SET_OBJ_IHF0 command is used by the backup application to 
set the file eyetem attributes of a file system object. The 
parameters associated with this conanand are described below: 



This parameter contains the DLE handle id of the DLB 
where the object resides. 

This parameter is complete DBLK and contains the 
object type, the object name, and the object attribute 
data which are to be set. 



The GRFS agent must set the following file system object 
attributes t 



gen_attr {file system attribute flags) 

The proper responBe message type is GRFS SET_OBJ_lHPO STAT. There 
are no parameters associated with this response mesBage. 



etime 
atime 
time 



(CREATION TIME) 
(ACCESS TIHB) 
(MODIFIED TIME) 

(Object data size) 



(if possible) 
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3.19 GRFS_VERIFy_OBJ_INFO, GRFS_VERIFy_OBJ_INFO_STAT 

The GRFS VEMPy 0BJ_INF0 command is used by the backup application 
^t^"?^r ^^L"^"" ^^'^ect attributes on the liirs^geSc 

match the object attributes contained on the backup media The 
parameters aaeooiated with this command are described b^ow; 

dle_id: -mis parameter contains the DLB handle of the DLE 

where the object resides. 

"v,/ <=°^lete DBLK and contains the 
object type, the object name, and the object attribute 
data which are to be coopared. -^""-b 

The GRPS agent must verify that the following input parameter DBLK 
fields match the actual attributes of the file ^st^^ect: 

cdate (CREATION DATE) 

mdate (MODIFIED DATE) 

size (object data size) 

gen_attr (file system attribute flags) 

rh& proper responee message type is GRFS VERIFY OBJ INFO STAT 
There are no parameters associated with thi^s resp^^e "i^agV 
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3.20 GRFS_PRSPARE_DBLK, GRPS_PREPARE_DBLK_STAT 

The GIIFS_PHEPARE_DBLK cominand is used eo that durinq restore 
operations the GRFS Agent is able to modif y (- ini^ge P^to 
directory names into a form vhich is us^le^ toe Sr^? 
(restore) agent's file systems. For instance, if aback™ s^ is 
created by a Macintosh agent, then the file and diScS/ nLel 
^»n.^: the backup set «Lt^ T^SI 

agent's PAT file system 8.3 format. 



dle_id: Tliis parameter contains the DLE handle of the DLB 
where the object resides. 

SiiLf^r^'^^'K^^w* =«»Pl«te DBLK and contains the 
object type, the object name. 



The agent should append the modified name at the end of the DBLK 
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;^pendix A - GRPS Technical Reference 

This section of the GRPS Technical Reference appendix shove 
the actual definitions of the Btruccures which have been 
described m this document. All of the structures can be 
found the GRFS.H include file. 



typedef xmioa 

INTS val [4] ; 

IHr32 num; 
} INET32; 

tvpedef union 

VJITTQ val 14] ; 

XmiT32 num; 
) UNET32; 

typedef union 

IHT8 val[2]; 
ZNT16 nxua; 
} 1HKT16; 

typedef union 

niNTS vaXt2]; 
UINTie num; 
) DMETIC; 

typedef struct 

DHET32 lew; 
X3NET32 msw; 
> UMET64; 

typedef CNBT 32 DLE_KAia)LB; 
typedef tJNET32 OBJ_HANI>LB; 
typedef TJIIKT32 SEQ_HANDLB; 

GENERIC DBUC HETWORK STRUCTORE 

Struct ^ grf s_gen_dblk^str 

PINTS bllc_type; 

CTIHTS reel; 

XrariB fg_com_reserver38] ; 

struct STD OBJ IHFO 
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niHTS 
UIKT8 
UINTS 

date time 
date'time 

DATE~TIHE 

DATE TIKE 

UHET64 

UNET32 

} Btd_info; 



os^ver; 

res2 12] ; 

ctime; 

atime; 

btiine; 

time; 

Bize; 

gen_attr; 



OB_inf o_coiiipi ete ; 
inin_ddb3inf o ; 
n>in_d<3b_Bize ; 
oe_spec~inf o ; 
oB_Bpec2Bize ; 
dBt)lk_actual_8ize ; 
tape~attrib8; 

~ naine_coirplete ; 
find_info; 
f ind~inf o_Bize ; 
cranslate'flag ; 
8pecial_£lag ; 



BOOLEAN 
DNETIC 
DNETIC 
UNET16 
DHET16 
DNETIG 
DNET16 
DHETie 
DNET16 
DNETIG 
BOOI£AN 
BOOLEAN 
niHT8 
union ^ 

struct OS DDB INFO 
{ " ~ 
O NBT1 6 
UNBT16 
11NBT16 
UNBTie 
} d! 

Struct OS FDB INFO 
{ " " 
BOOLEAN 

DNBne < 

DNBT16 1 

} f; 



08_path; 

os_path_leng; 
path_leng; 
path; 



grf s_gen_dbllc_Btr GRPS_GEH_DBLX, 



struct gr£s_inessage 

UINTB insg^type; 
UIMT8 reBeirved; 
UINTie retco(te; 
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requeet_i<S 



D1JET32 
union { 

/** GRFS conmand parameter 

dlb kanple 
obj_handi.b 

grfs_attach_di.e_parms 

grfs_flnd_first_obj_parms 

grfs_object_pabms 

grfs_open obj_parms 

grfs_read~obj_parms 

grfs_writI_obj farms 

grfs_verify_obj_parlis 

ghfs_seek_obj_parms 

grfs_change_dir_parms 

grfs_endm_spbc_pahms 

/*• GRFS response parameter 
OHET32 

GRFS_GEN_DBIjK 
GRFS_A-ITACH_DLK_STAT_PASMS 
GRFS_FIND DLE_STAT_PARMS 
GRFS_FIHD~OBJ_STAT_PARMS 
GRFS_0PEM obj_stat PAHMS 
grfs_rkad3obj_stat~pahms 
grfs writb obj_stat_parms 

GRFS~VERIFV_OBJ_STAT_PAiaiS 
GRFS BNUH SPEC STAT PARKS 
, } ~ ~ ~ " 



structures **/ 
dle_id; 
obj_id; 
attach_parms ; 
f f _ob j_paiinB ; 
ob3_partnB; 
open_ob j _parmB ; 
read_obj parms ; 
write_ob3_paziiis ; 
verif y_obj_pcirTn8 ; 
BeGk_obj jpanns ; 
change_dir jparms ; 
enuin_Bpec_parTnB ; 

structures **/ 
seek obj offset; 
dblk? ~ 
attach_Btat ; 
f ind_dle_Btat ; 
f ind_obj_8tat ; 
ppen__obj_Btat ; 
read~ob j~stat ; 
write_obJ_Btat : 
verif y_obj_Btat ; 
enuin_Bpecial_Btat ; 
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This section shows the GRFS command message types and their 
corresponding GRFS response message types. The parameters 
associated with each message are also provided. 



GRFS COMMAND MESSAGES 



GRFS RESPONSE MESSAGES 



GRFS_ATTACH_DLE ( dle_naine [J , GRFS_ATTACH_DLE_STAT( dle_id, 
bee_flagB, max connects, 

Bpecial_word, max_opens_per_eonnect, 
»ax_obj_bsize, process_ddb6, 
dle_parent, max_obj_bsize, 
'="T>'^_':ype ' cinpr_type , 

user_name I) , BupportB_children 
password tl ) path_len , 

current_path [] ) 

GRFS_FIHD_FIRST_DLE ( dle_id) GRPS_F1ND_DLE_STAT ( die nati w. [] , 

path_delim, ~ 
passwd_reg, 
user_reg, 
dle_writeable , 
8upports_last access, 
os_id, 

{B~type, 
crypt_type, 
cinpr_type, 
more_flag) 

GRFS_FIND_HEXT_DLE [ dle_id) GRFS_FIND_DLE_STAT ( dle_naine [1 , 

path_deliin, ~ 
passwd_req, 

dle_writeable , 

OB_id, 

os_ver, 

fB_type, 

crypt_type , 

cn?Pi^_type, 

inore_flag) 

GRPS_DBTACH_DLE { dle_id) GRFS_DETACH_DLB_STAT ( ) 

GRFS_FIND_FIRST_OB J ( dle_id, GRrS_FlND_OBJ_STAT < more_flag, 
find_t^e, dblk) 



GRFS_FIND_CIiOSE ( 
GRFS_CRKATE_OBa { 
GRFS_OPEN_OBJ< 



GRFS_FIND_OB J_STAT ( 
GRFS_FIin)_CIiOSB_STAT { 
GRPS_CREATB_OBJ_STAT { 
GRFS_OPEN_0BJ_STAT ( 



dblk) 
---) 
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GRFS_REM)_OBJ ( 



GRFS_WRITE_OB J ( 



>_SBBK_OBJ { 
5_VKRIFy_0B J ( 



GRFS. 
GRFS 



_CLOSE_OB J ( 
DELETE OBJ< 



obj_id, 

Bize, 

Offset) 



obj id, 
size, 
offset, 
stm_info, 
buffer []) 



obj_id, 
size, 
offset, 
stnn_info, 
buffer []) 

obj_id) 



GRFS_READ_OB J_STAT ( size, 

blJc_Bize, 
stnn_inf o, 
buffer!] ) 

GRFS_WRITE_OBJ_SrAT { size, 

bl)c_size) 



GRFS_SEEK_OBJ_STAT( Beek_obj_Of f Bet) 



GRFS_CIjOSB_OBJ_SXAT ( - - - ) 
GRFS_DEI.ETE_OBJ_STAT ( - - - ) 



GRFS_CHftHGE_DlR( dle_id, 

net_path [] 
size) 

GRFS_GBT_CDR_DDB ( dle_id_) 



GRFS_GBT_OBJ_IHPO_STAT { dblk) 

GRFS_VERIFY_OBJ_INFO_STAT ( ) 

GRFS_C3iANGE_DIR_STAT ( ) 

GRFS_GET_CUR_DDB_STAT ( dblk) 
GRFS_SBT_OBJ_INFO_STAT ( ) 



GRFS_BHDM_SPBCIAL_FIRST 

{ dle_id, 
enuin_type) 

GRPS_BOTH_SPBC1AI._1JBXT 

(dle_id, 
enxnn__type) 

GRFS_SPECIAL_EXCLODE 

(path_len, 
foame len, 
data ID 

6RFS_PREPARE DBLK 



GRPS_ENnM_SPEClAL_STAT ( name [1 , 

more_f lag) 



GRPS_ENDM_SPECIAL_STAT ( name (] , 

~ ~ iiiore_flag) 



GRFS_SPBCIAL_EXCLTOB_STAT ( - - - ) 



GRPS_PHEPAHE_DBIJC_STAT ( dblk> 
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CCJMMON GRFS MESSAGE PROCESSING 

All GRFS meseagee generated by the backup application include the 
following common fields: msg_type, retcode, and regiiest_id. The 
insg_type field must contain a valid GRFS command value. The 
backup application will set the 2-eqruest_ad field to a value which 
the backiqj application will use to correlate outgoing GRFS conanand 
messages to the corresponding incoming GRFS response messages. 
The GRFS agent must set the requeBt_id value of the GRFS response 
mesBage to the request_id value received in the corresponding GRFS 
command mesBage. The GRFS response message to the requeet_id 
value received in the corresponding GRFS command message. The 
ret_code field is not used for GRFS command meBsagea; it is 
meaningful only for GRFS response messages. 

Several of the message parameter structures contain large fields 
(DBLKs, full -path namea) which are defined statically but contain 
variable length data, and these data fields will typically fill 
only a small portion of the allotted space. These large fields 
are always declared as the last member in the parameter structure . 
Only the portion of the message parameter field which is actually 
used must be transmitted across the network. This will allow the 
GRFS to be more efficient because most non object-data GRFS 
mesBages can be transmitted as a single HRl transport packet. 

CRITICAL ERROR HANDLING 

GRFS agent programs must handle critical error situations without 
hanging the agent's system . When a GRFS agent detects a critical 
error while performing an GRFS ccanmand, the agent program should 
"fail" the operation and set the retcode field appropriately 
(FS_DEViCB_ERROR, etc) , The agent can also retry the failed 
operation before returning a GRFS status message to the baektjp 
application. When a fatal FS error code is returned to the backup 
application, the application user will be given the opportunity to 
decide whether to retry the failed operation. 
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GRFS MesBages Type Values 



GRFS COMMMTOS 



GRFS_ATTACH DLE 


0x01 


GRFS~FIND FIRST DLE 


0x02 


GRFS FIND NEXT DLE 


0x03 


GRFS DKTACH DLE 




GRFS FIND FIRST OBJ 




GRFS FIND NETT OBJ 


0x06 


GRFS FIND CLOSE 


0x07 


GRFS_CREATE OBJ 


0x08 


GRFS~OPEN OBJ 


0x09 


GRFS~READ OBJ 


OxOA 


GRFS WRITE OBJ 


OxOB 


GRFS~SKBK OBJ 


OxOC 


GRFS VERIFY OBJ 


OxOD 


GRFS CLOSE OBJ 


OxOE 


GRFS DBLBTB OBJ 


OxOF 


GRFS~GET OBJ IHFO 


0x10 


GRFS VERIFY OBJ INFO 


0x11 


GRFS CHANGE DIR 


0x12 


GRFS GET CDR DDB 


0x13 


GRFS SET OBJ IHFO 


0x14 


GRFS ENDM SPECIAL FIRST 


0x15 


GRFS_B1ICIM_SPECIAL NEXT 


0x16 


GRFS SPECIAL EXCLUDE 


0x17 


GRFS PREPAHB~DBLK 


0x18 



GRFS RESPONSES 

GRFS_ATTACH_DI.E_STAT 
GRFS FIND_DLE_STAr 
GRFSJ5ETACH_DLE_STAT 
GRFS_FIHD_OBJ_STAT 
GRFS~FIND_CLOSE_STAT 
GRFS_CREATE_OBJ_STAT 
GRFS_OPEN_0BJ_STAT 
GRFS_READ_OBJ_STAT 
GRFS_WRITE_OBJ_STAT 
GRFS_SEEK_OBJ_STAT 
GRFS VERXFy_OBJ_STAT 
GRFSlCLOSB_OBJ_STAT 
GRPS_DELBTB_OBJ STAT 

grfs_get_obj info stat 
grfs~vbrIfy obj_i5fo_stat 
csrfs~changb3dxr_stat 
grfs_gbt_cur ddb_stat 
grfs_set_obj~info_stat 
grfs endm_special_stat 

GRFS~SPECIAL_EXCLDDB_STAT 

grps_prepare_dblk_stat 



0x41 
0x42 
0x44 
0x45 
0x47 
0x48 
0x49 
0x4A 
0X4B 
0X4C 
0x4D 
0x4B 
0x4F 
0x50 
0x51 
0x52 
0x53 
0x54 
0x55 
0x57 
0x5 B 
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GRFS COMMAND MESSAGES 
GRPS_ATTACH_DLB 



GRPS_PIBD_F1RST_DLE 
GRFS_FI1ID_NBXT_DIjE 
GRFS_DETACH_DLE 
GRFS_FIHD_FIRST OBJ 



MESSAGE PARAMETER STRPCTDRE 

Struct GRFS_ATTACH_DLE_PAHMS 

C3iflR dle_naine [GRFS_MaX_DLE_NAME_LEH] ; 

INET16 bec_flagB 
INET16 Bpeeial_word; 
DNETIS xnax_obj_bsize ; 

DLE_HANDLE dle_parent ; 
nnJTEa cinpr_type ; 

CHAR UBer_name [48) ; 

CHAR pasGword [MAX_PASSOWRD_LEN) ; 

DLE_HAND cile_idi 

DI.E_HAND dle_id 

DLE_HflND dle_id; 

struct GRFS_FIND_FIRST_OBJ_PAR«S 

DLE_HAHr) die . id; 
DNET16 f ind_type ; 

CHAR sname [GRPS_MAX_SNAMBl ; 



GRFS_PlHD_HEXT_OBJ 

GRFS_PIHD_CLOSB 

GRPS_CREArE_OBJ 

GRFS_DEI.BTE_OBJ 

GRFS_GET_OBJ_INFO 

GRFS^VBRIFY OBJ XHFO 

GRFS_SET_OBJ_INFO 

GRFS_OPEN_OBJ 



GRFS_RKflD_6BJ 



GRFS_WRITE OBJ 



struct GRFS OBJECT PAEMS 
{ 

DLK_HAHD d] 
GRFS_CEN_DBIiK dl 



Struct GRFS_CPEN_0BJ_PAH1IS 



{ 

DI£ HARD 
IMET16 

GRFS GEB DBLK 



dle_id; 
mode; 

xesezved[2] ; 
dblk; 



struct GRPS_RBAD_OBJ_PARMS 



OBJJtMUD 

OHET16 

DMBT32 



obj_id; 

size; 

offset; 



struct GRPS_WRITE_OBJ_PARMS 
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OBJ_HAND 
DNET32 
STRKAM_INFO 
ONETlS 



obj_ici; 
offset; 
Btrtti_inf o; 
size ; 



UINT8 buffer [GRFS_MIN_OBJ_SIZE] ; 



GRFS SEEK_OBJ 



GRFS_VERI FY_OB J 



Etruct GRFS SEEK OBJ PAKHS 
{ " " " 
OBJ_HAUD obj_i( 
DNET32 offset 

); 

struct GRFS_VBRIFy_OBJ_PARMS 



OBJ_HAND 
nNET32 
STREMa_lKPO 
UNETIS 



Obj_id; 
offeet; 
stnn^infi 
size; 



U1NT8 buffer [GRFS_MIN_OBJ_SIZB) ; 



GRFS_ajOSB_OBa 
GRFS_CHANGE_DIR 



OBJ_HMqD obj_id 

Struct GRFS CHANGE DIR FARMS 
{ ~ ~ ~ 

DLE_HAND die id; 
INET16 size; 

CHAR net_path{GRFS_MAX_PATH_IiEN] ; 



GRFS_SPECIAL_BXCIXIDB 



Struct GRFS ENDH SPEC PARHS 
( " " ~ 
DLE_HaHD dle_id; 
D1IET16 eiiuin_type ; 

struct GRFS SPEC EXCZ.UDE PARUS 
{ " " 

INBTl 6 path_len ; 

INET16 fnaine_len; 
UIMT8 buffer [GRFS_MIN_0BJ_SIZB1 ,- 
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GRFS RESPONSE MKRfiflrrgg MESSAGE PARAMETER STRnCTTTRR 

GRFS_ATTACH_DLE_STAT B Cruet GRFS_A'rrACH_DLE_STAT_PAEMS 

r)LE_HAND dle_id; 
INBTIS ina3c~connectB; 
INET16 inax_opeiie__per_connect ; 

DNEtTg procesB_ddbs ; 

1NET16 inax_obj_bsi2e; 
BOOLEAN ei?5portB_children; 
DNET16 path_len 
OIHXa cmpr_tYpe ; 

CHAR current nath [GaFS_MAX_PATH_LEN) ; 



GRFS_FIND_DLE_STAT Struct GRFS_FIKD_DLE_STAT_PARMS 

C31AR dle_name tGRFS_MAX_DLB HAMB_LENJ ; 

CHAR path_deliin; 

tJINTS res! ; 

BOOLEAN passwd_req; 

BOOLEAN user_req; 

BOOLEAN die writeable; 
BOOLEAM last_acce88_sxipported; 

1IIT8 OB_id; 

INT8 OB ver; 

INET16 f 6~type ; 

DlHTfl crypt_type ; 

UIHT8 cii?}r_type ; 

BOOLEAN inore_flag 



GRFS_DETACH_DLE_STAT none 

GRFS_PIND_OBJ_STAT struct GRFS_FIHD_OBJ_STAT_PARMS 

BOOLBAH inore_flag; 
OIKTS reeerw©d[2) ; 

GRFS_GEN_DBLK dblk ; 



GRFS_FIHD_CLOSE_STAT none 
GRFS_CHEATE_OBJ_STAT none 

GRFS_OPEH_OBJ^TAT struct GRPS_OPBN_OBJ_STAT_PARMS 

OBJ HAND Obj.id; 
GRFS_GBN_DBLK dblte; 



GRFS_READ_OBJ_STAT Struct GRPS READ OBJ STAT PARMS 

^ - - - - 
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GRFS_WRITE_OBJ_STAT 



GRFS_SEEK_OBJ_STAT 
GRFS_VERIFY_OBJ_STAT 



GRFS_CLOSB_OBJ_STAT 
GRFS_DELETE_OBJ_STAT 
GIlFS_GET_OB J_IHPO_STAT 
GRFS_VERI FTf _OB J_INFO_STAT 
GRFS_CHWIGE_DIR_STAT 
GRFS_GET_ajR_DDB_STAT 
GRPS_SET_OBJ_INPO_ST&T 
GRPS_ENaM_SE'BClAL STAT 



0NET16 eiae; 
tJNBTie blk size; 

STRKAM INFO strni inifo; 

UINTS bu£ferTGRrS_MIN_OBJ_SIZE] ; 



GRFS_WRITB_0B,7_STAT_PARMS 



ONET32 Offset 

struct GRFS_VBiaFy_OBJ_STAT_PABMS 



size; 
blk_size; 



none 
none 

GRFS_GEN_DBLK dblk; 

none 

none 

GRFS_GKN_DBLK dblk; 

struct GRFS_ENDM_SPECIALp_STAT_PARMS 

BOOLEAH more. flag; 

INKT16 path Ian; 

INETie £naiiie_len ; 

UINTS buffer [6RPS M1N_0BJ_S12B] ; 
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GRFS RETDRN CODES 

The following values have been defined for GRFS agents to us 
return codes in the retcode field of GRFS response messages: 

SUCCESS 0x0000 

ODT_OP_MEMORY OxFFFF 

FS_NEVBR_ATTACHED OxFEOl 

FS_HAD_DBIiK bxFE02 

FS_DLE_NOT_A'rTACHED OxFE03 

FS_STACK_KMPTy OxFE04 

FS_ACCSSS_DKNIED OxFEOS 

PS_ODT_OF_SPACE OxFKOC 

PS_N0_M0IIB OXFE07 

FS_110T_F01JUD OxFEOG 

PS~IHVALID_DIR OxFEOS 

FS_AT_RO0T OxFBOA 

FS OBJECT_HOT_OPKIlBD OxFEOB 

FS KOF_HEACHBD OxFEOC 

PS_DEVICB_ERHOR OxFKCD 

PS_GDATA_ptFFERKirr OxFKOE 

FS_SECDRlTr_DIFFERENT OxFEOF 

FS_OPBIJBD_INDSE OxFElO 

FS_IN_OSB_ERROR OxFBlI 

FS_INFO_DIFPEREMT OxFB12 

FS_BDFFKR_TO_SMaLI. 0xFE13 

FS_DBFADLT_SPBCIPIED OxFEl4 

PS_RESnATA_DIPFBRBNT OxFKlS 

FS_INCC»ffiATlBLB_OBJECT 0xFE16 

FS_HOT__IHITIAIjIZED OxFE17 

FS_DNDEFIlJBD_nrPE OxFElS 

PS_NOT_OPEN 0xFE19 

FS_INVAIiID_DIiB OxFElA 

FS_HO tK}RE~DIiB OxFElB 

FS_BA5_DLB~HAND OxPElC 

FS_DRIVB_1JST_ERR0R OxFElD 

PS_ATTACH_TO_PARENT OxFElE 

PS_DBVICB_NOT POOND OxFElF 

FS_BAD_IHPnTj5A.TR OxFE20 

FS_OS_ArTRZBrDIFFER 0xFE21 

INV»I.It!_PATH_DESCRIPTOR 0xFE22 

1NVAL1D_FII,B_DBSCRIPT0R 0xFE23 

DRIVB_DESCR1PT0R ERROR 0xFE24 

FS_ KO_M ORB_COHMKCTIONS OxFE25 

FS_SBHVER_ADDR_HOT_PODHD 0xPB26 

PS_BiaX_SERWBR_COiniECTIONS OxFE27 

PS_BAD_ArEaCH TO_SERVER 0xFB28 

PS_ BftD_ SBRVBR~LCX3m 0xFB29 

FS_SBIWER_10GOTTJDENIBD OxFB2A 

FS_BAD_ATni_RBAD OxFB2B 

PS_EAnAIA_DIFFBREHT 03eFB2C 

FS_OBJBCT_CORHnPT 0xFE2D 

FS_ACLDATA_DI KPKKBN T 0xPB2E 

PS_CHIliDRBN_KOT_C(»!PLETE 0xFE2F 

PS_COMM_FAlM3HB 0xFE30 

FS_NST_DBV_BRHOR OxFE31 

FS_DOHT_raMT_STREMl OxFBBl 
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The following section provides a list of likely return code values 
for each of the GRFS reeponee meeeages. GRFS agente should use 
the return value listed above which provides the best indication 
for the cause of an error. 



The user or password field was not 
valid. 

The dle_naine was invalid 



GRFS FIND_DLE_STAT 
" FS_IKVALID_DI.E 
FS_NO_IIORS 

GRFS_DETACH_DI.E_STAT 
PS_INVM.ID_DLE 

GRFS FIND OBJ STAT 

~ FS_INVai:iD_DLB 
FS_NO_M0RB 



dle_id was invalid 

No more DLEs to enumerate 

dle_id was invalid 

dle_id was invalid 

No more file system objects to 

enumerate 



GRFS_CREarE_OBa STAT 
~ FS_INVALID_DLB 
FS_DEVICE_ERROR 



dle_id was invalid 



dle_id was invalid 
"hard" device error. 



FS_ACCESS_DEIIIED 

FS_BAD_DBLK 

GRFS_OPEH_OBa_SrAT 

~ FS_OPENED_INCTSB 

FS_XN_DSB_EKROR 



FS INVai:.ID OLE 

Fs~Ncn' FcdSo 

FslDBVXeB_ERROR 



OOr_OF_MBMORY 

GRPS_READ OBJ STAT 

~ FS_DBVICB_ERROR 

FS_OBJBCT_N0T OPENED 
FS EOF REACH^ 
FS ACCESS DENXEO 



grps_mritb obj stat 

~ fs objbct hot_opbnbd 
fs^deviceIerror 



Agent doea not have pexmissi 

create object 

The DBLK data is invalid 



Object already opened by another 
process, but not locked, and 
BBC_CONPIG flag 
BEC_BACian>_PlI.ES_IK_nSE is set 
Object already opened by another 
p r o e e B B and locked, 
BEC_BACKDP FILES IK USE not set 
dle_id was invalid ~ 
Object not found 

"hard" device error, .unable to open 
object 

The DBLK data was invalid 

Agent does not have pezmissioa to 

open object 



"heird" device error read 

parameter was invalid 
End of File already reached 
Agent does not have permission 
read object 



obj_id parameter hot invalid 
"hard" device write error 
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FS_OBJECT_NOT_OPENED obj_±d parameter was invalid 
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FS_DONT_WANT_STREAM 

GRFS_SEEK_OBJ_STAT 

FS_OBJECr_K0T_0PENED 

FS_BOF_RKACHBD 

FS_DBVICE_ERROR 

GRFS_VER1FY_0BJ_STAT 

FS_OBJKCT_NOT_OPENED 
FS_DKVICE_EHROR 
FS_KOF_RKACHED 
FS_GDATA_DIFFBRBNT 

FS_SBCDR1TY_DIFFEREKT 

FS_EADATA_D1FPERENT 

FS_DONT_WANT_STREAM 



GRFS_CLOSE_OBJ_STAT 

FS_OBaKC:r_HOT_OPENED 
FS_DBVICE_ERROR 

GRFS_DBriBTE OBJ_STAT 

fs ihvaijcd dle 
ps3hot_fotod 

FS_DBVICE_BRHOR 

FS_BAD_DBLK 
FS_ACCESS_DEKIED 

GRFS_GBT_OBJ_INFO STAT 
FS INVALID DLE 
FS~HO_KORB 
PS_DBVICB_BRROR 



FS_BAD_DBIJC 

GRFS_VBRIFyjOBJ_IHPO STAT 
PS_INVAIilD DLB 
PS_HOT_FOn5D 
FS_DBVICB_BRROR 

FS_BaD_DBLK 
FS_INFO_DIFFERE»T 



GRPS_CHMIGE_DlR_STaT 
FS_INVALID DLB 

fs~invaij:d~dir 
fs_dbvice_brror 



Device is full 

Agent does not have permission to 
write object 

Agent does not want to restore this 
data stream 



ob3_id parameter was invalid 
End of File already reached 
"hard" device seek error 



obj_id parameter was invalid 
"hard" error 

End of File already reached 
Object's nozmal data atream does 
not match 

Object's security data stream does 
not match 

Object's extended attribute data 
stream does not match 
Agent does not support this data 
stream type 



dle_id was invalid 
Object not found 

"hard" device error, unable to 

delete object 

The DBLK data was invalid 

Agent does not have permission to 

delete object 

dle_id was invalid 
Object not foimd 

"hard" device error, unable to 

delete object 

The DBLK data was invalid 

dle_id was invalid 
Object not found 

"hard" device error, unable to scan 
device 

The DBLK data was invalid 

The object's attributes do not 

match 



dle_id was invalid 

net_path 0 too long, or new path 

does not exist 

"hard" device error, tmable to scan 
device 
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GRFS GET_CDR_DDB_STAT 

FS_1NVALID_DLE dle_id was invalid 

FS_DEVICE_ERROR "hard" device error, unable to scan 

device 

dle_id was invalid 
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The individual fields within the GRFS common DBLK structure 
beiw """^^ manipulated by GRFS agent programs are described 

blk_type: Defines whether the object is a file or a 

directory. 

files z= 08 

directories = 09 



Ctime: 
btine : 

time: These four fields are all defined as type DATE time 

structures. The DATE_TIMB structure has the follSwinq 
format: ^ 

struct DATE_TIME { 

UINn6date_valid; /*TRUE or FALSE •/ 

Uiwneyear; /*year since 1980 */ 

DlNTiemonth; /* 1 to 12 */ 

OINTlGday; /* 1 to 3X */ 

DINTlChour; /• 0 to 23 */ 

DINTieminute; /* 0 to 59 */ 

niNTiesecond; '/* o to 59 */ 

OIHTieday_of_wee)t; /* a to 7 Sun to Sat */ 

ctime = Object CREATION time 
atime = Object ACCESSED time 
btime = Object archived time 
time = Object MODIFIED time 

If the OS of GRFS Agent being developed does not 
support one or more of the specific time stanros, 
then those time stan^) fields should be reset to 
all zeros. 

The size field contains the size of the normal 
data associated with the object. For instance 
the OS/2 Agent does HOT include the size of BAs 
and ACliS associated with an object. 

gen_attr: This field is a bit-mapped flag which describes 

the file system attributes of the object. The 
fieid*^"' ^1*9 values can be contained in this 

FIIjE_NORMaL 0x0000 

F1LK_READ0NLV 0x0001 

FII.BJIDDEH 0X0002 

TIUB SYSTEU 0x0004 

FILE'dIRBCTORY 0x0010 

F I LiB_ARCHIVED 0x0020 

os_info_con?3lete This field is a boolean value which must be set 
to TRDE when the all the DBLK information for an 
object has been filled in. 
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inin_ddb_anf o This field contains a pointer to the information 

in the DBLK data area vhieh is required to 
perform either a GRFS_GET OBJ IMFO or 
GKFS_PIND_NBXT_OBJ conwiand. The information 
pointed to by this field must be contiguous 
within the data area. Typically the DBLK -find 
information and the object name constitute the 
"iaN_DDB_INFO" . The DBLK find information is 
deecribed in the find_info DBLK field. 

min_ddb_eize This field contains the number of byteB of data 

pointed to by the inin_ddb_inf o field. 

oB_Bpec_inf o This field contains a pointer to the DBLK data 

area which contains any OS specific information 
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that the GRFS agent would like preserved during 
r?'^^)??/^'^ restoration operatione. For instance 
the OS/2 agent uses this area to save HPFS "Long 
Names" when they are present. ab another 
exaji5>le, a Unix GRFS agent could use this field 
to save xnformation about special device 
placeholder files. 

OB_epec_Bi2e This field contains the number of bytes of data 

pointed to by the oB_Bpec_irif o field. 

dblk_actual_si2e ^is field contains the size of the entire DBLK 
I^xs value xs the sum of the size of the GRFS 
DBZ.K common stnicture and the number of bytes of 
data within the variable length DBLK data area 
Remember that the total DBLK must at most 1024 
bytes long. 



ts^_attribs 



f ind_inf o_B i ze 



tran8late_flag not used 



not used 

l^^^Ji^^^ contains a pointer to the information 
in DBLK data area which can be used by the GRFS 
agent to perform a GRFS_FIND_»EXT OBJ command 
Exanples of this field are the DOS GRFS agent 
passing a OTA structure and the OS/2 aqent 
passing the DosFindPirstOHDIR value. 

This field contains the number of bytes of data 
pointed to by the find_info field. 



b.d.os_path This field contains a pointer to the path string 

contained within the DBLK data area for a 
directory object. The path string sho\ad not 
begin with a path delimeter character unless it 
IS the root directory of a DLE. The path string 
must be null -terminated. During backup 

os_path field and the path field 
will be identical. During restore pperations, 
the o8_path field will represent thi - source i 

^H^-^^t "*? ^^^^^ represent the 

"destination" path. 

b.d.os_path_leng This field contains the. length of the path 
pointed to ^ the os_path field. This value 
should include the null -termination character. 

b.d.path_leng Tliis field contains the length of the path 
pointed to by the path field. This value should 
include the null-texmination character. 
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b.d.path This field contains a pointer to the path string 

contained within the DBLK data area tor a 
directory object. The path string should not 
begin with a path delimeter character unless it 
is the root directory of a DLE. The path string 
must be null -terminated. During backup 

operations, the path field will be the same as 
the os_path field; however during restore 
operations the path field may be different than 
the OB_path field. 

b.d.inuse_attrib This field contains a flag which is used to mark 
files which have been opened but the file is 
currently also qpened by another process. 

b.f.OB_name This field contains a pointer to the file name 

string contained within the DBLK data area for 
a file object. Ttie path string must be null- 
ter m inated. The 06_naine field abd the name 
field will be the sane during backup operations. 
During restore operations the os_najne field 
represents the "source" file name whereas the 
name field represents the "destination" file 
name. 

b.f .name This field contains a pointer to the file name 

string contained within the DBUC data area for 
a file object. Hie path string must be null- 
terminated . 

Whenever a GRFS agent returns a DLE's logical root directory 
object DBLK, the DBLK data area path string should be set to 
'\0' and the b.d.os_path_leng field should be l. 
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What is claimed is : 

1 1. A computer network, comprising: 

2 a) a plurality of coitiputers running disparate 

3 operating systems, respectively; 

^ b) a storage device for backing up and 

5 restoring data processed on the network; and 

^ ^> means for performing backup to and restore 

7 from the storage device, including: 

8 i) a GRFS file system running on one of 

9 the said computers; 

^° a plurality of GRFS agents each 

11 running on a respective one of said computers; and 

iii) wherein said GRFS file system and 

13 each of said GRFS agents interface with one another via 

14 command and response messages, respectively, said command 

15 and response messages being structured to support the 

16 disparate operating systems. 

1 2. A computer network, according to claim 1. 

2 wherein said disparate operating systems have different 

3 data structure alignments, and said command and response 

4 messages are structured with a least common denominator 

5 alignment for said disparate operating systems. 

1 3. A computer network, according to claim 1, 

2 wherein said command and response messages are further 

3 structured to interchange data between said disparate 

4 operating systems. 
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1 4. A conputer network, according to claim 3, 

2 wherein said interchange structure of said command and 

3 response messages enable data from one of said computers 

4 running one of said operating systems to backed up to 

5 sa;id storage device and said backed up data to be 

6 restored to another of said cortputers running another of 

7 said disparate operating systems. 

1 5. A computer network, according to claim 3, 

2 wherein said interchange structure of said messages 

3 includes a streamer header having an identification value 

4 determining whether an associated data stream type is 

5 supported by a given one of said disparate operating 

6 systems. 

1 6. A conputer network, according to claim 1, 

2 wherein said command and response messages are further 

3 structured to enable independent multiple users of said 

4 plurality of computers to request simultaneously backup 

5 or restore of the data. 

1 7. A computer network, according to claim 6, 

2 wherein said command and response messages are structured 

3 with a request id and wherein said GRFS file system may 

4 create a unique request id for every GRFS command 

5 message, whereby the GRFS file system can communicate 

6 simultaneously with multiple GRFS agents. 

1 8. A computer network, according to claim l, 

2 wherein said plurality of computers each has a user 

3 interface to enable a user to select backup or restore of 

4 selected data. 
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1 9- A computer network, according to claim l, 

2 wherein said network may have an additional computer not 

3 running a GRFS agent. 
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EXAiffLE 1: To bockup o single 5000 byie file 
Job Manoqer Conmiond Messoges 



ATTACH_DLE( dle_n(me = "DougConpoq" 
dle_p(irent = KULL 
iDox_obj_bsize = 32768 . 

^password = >enSesane") 



MESSAGE m DIAGRAM FOR BACKUP 
GRFS Agent Workstation Response Messoqes 



FIND.FIRST,DLE( diejd = 01) I 



AnACHJ)LE_STAT( die.id = 01 I 
children = TRUE 
iiox_obj.bsize = 2048) 



AnACHJLE( die.noiiie = 'DriveC 
dle_porent = Ot 
inax.obj.bsize = 32768 

password = Wl") 



FIND.FIRST.DLE.STAT( dlcnome = "DrmZ" 
posswd.req = TRUE) 



ATrACH.DLE_STAT( die.id = 04 

children = FALSE 
iiiox.obj_bslze = 2048) 



FINO_FIRST_GBJ( die.id = 04 




FIND.OBJ_STAT( norej log = TRUE 


snaie ="♦.»") 




dblk (noi!ie=COMMAND.C0M)) 



0PEN.0BJ( die.id = 04 

mode = REAO.ONLY 

dblk (noiiie=eotWAND.COM)) 



OPEN_OBJ_STAT{ ob].id=42 

dblk (noiie=COWUAND.C0M)) 



READ_OBJ( obj.id = 42 
size = 2048) 



READ.OBJ_STAT( size = 2048 

strB_header = NORMALOATA 
buffer[] ) 



READ_OBJ( obj_id = 42 
size = 2048) 




READJ)BJ.SrAT( size = 2048 

strB.heoder = INVAUD 
bufferO) 




READ.OBJ( objjd = 42 
size = 904 ) 






L 


REAO_OBJ_STAT( size =904 

slrajeader = INVALID 
bufferQ) 


CLGSLOBJ( obi.id-42) 
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EXAMPLf 2: To restore o single 5000 byte file. MESSAGE FLOW DIAGRAM FOR RESTORE 

Job Monoqer Conmond Messoqes GRFS Agent Workstotion Response Messag es 



ATTACH J)LE( dle.nonie = "DougCorapoq" 
dle.porent = MULL 
flox_obj_bsize = 3276B 
password = '^penSesanie") 



AnACH.DLE.STAT( diejd = 01 

children = TRl£ 
inox_obj_bsize = 204B) 



FIND.FIRST_DLE( dIeJd = 01) \ 



AmCHJIE( dlcnome = DriveC" 
dle_porent = 01 
inax_obj_bsizc = 32768 
password = TO!") 



FrND_FIRSTJ)LE.STAT( dlcnome = "DriveC" 
posswd.req = TRUE) 
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